EnigmA Amiga Run 1995 October/EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso/Aminet/misc/emu/prlink_080b.lha/prlink-0.8.0b/README

Text File | 1995-06-07 | 14KB | 318 lines

prlink v0.8.0 -- a data transfer system for Commodore 8-bit computers
                 and a 386 clone running Linux

Release date: 10th May, 1995
Copyright © 1994, 1995 Marko Mäkelä and Olaf Seibert
Original Linux and Commodore 64/128/Vic-20 version by Marko Mäkelä
Ported to the PET and the Amiga series by Olaf Seibert

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


PREFACE

This document describes the first public release of our prlink utility,
a program package that lets you to copy memory blocks to and from the
memory of a Commodore 8-bit computer.  The document is very clumsy right
now, so feel free to write a better version and send it to us if you like
this program. :-)

Currently daemons are available for the Commodore PET series, the Vic-20,
C64 and C128 computers, and there are compilation options that support the
Commodore REU, even simultaneously with an Action Replay cartridge installed,
and some internal memory expansions on the C64 and the C128.

The client programs are written so that they should compile on MS-DOS
fairly easily.  The programs are written for Linux, and there are machine
language versions of the transfer routines for i386 compatible processors.
The software also compiles on the Amiga, and the Amiga transfer routines
are written in 68000 machine language.

The idea of the transfer utility package is that a daemon runs on the
Commodore side in an interrupt routine, without blocking the computer.
It checks if the PC wants to send any command, and executes possible
commands.  There are commands for loading and saving memory blocks, for
jumping to a machine language program and for starting a BASIC program.
The latter two commands deinstall the daemon for maximum compatibility.

With the current protocol, it is be possible to make useful
applications that run on the PC, like a disk copier (with ZipCode
compression and decompression if desired), and a machine language monitor.
It is already possible to develop Commodore programs on the PC, and to
transfer them over to be tested out.  Actually, this is exactly how the
prserver.asm and prsample.asm programs have been developed.  I use my
the dasm assembler, ported to ANSI C by Olaf Seibert, which supports
conditional assembling and multiple source modules.  It can be retrieved
from ftp.funet.fi, as /pub/cbm/programming/dasm.tar.gz.


PROGRAMS

Following client programs are available:

  basic loader: This is a BASIC listing that you can type in on your C=
                computer in order to bootstrap the prlink utilities.  You
                will only need this one if you don't have any other
                possibility to transfer the prserver program to your C=
                computer.

  prload:   Loads a Commodore-style program file to the remote computer.

  prsave:   Echoes the contents of a C= memory area to standard output.

  prcart:   Loads and starts Vic-20 cartridges.  Takes its input either
            from the standard input, or from files that contain the 8kB
            ROM images for $A000-$BFFF and $6000-$7FFF.  Patches the
            Autostart code so that RESET will work, and start the transfer
            daemon again.

  prsample: Plays a 8-bit sample file on the remote computer, cutting
            the four least significant bits off.  Does not try to handle
            the sampling frequency, so it's useful only for testing the
            link.

  prrfile: Reads a file from C= disk to local disk.
  prwfile: Writes a file from local disk to C= disk.
  prdisk: Reads or writes whole C= disks to/from local files.  All sizes
          of drives are supported.  The only requirement is that the
          first track is 1 and the first sector on each track is 0.  Tracks
          and sectors increment up to 999.

You can find the command usage out by using the -h switch in each program.

The prload and prsave commands have a -b switch that specifies the memory
bank.  Bank numbers 0 to f are for internal memory.  The two lowmost bits
are for specifying the MMU mapped memory bank on a C128.  In other words,
MMU mapped memory banks on the C128 are numbered from 0 to 3.  On
unexpanded C128s, the banks 2 and 3 are the same than banks 0 and 1.

The bits 2 and 3 of the bank number specify the PIA mapped expanded memory
bank on a C128 or a C64.  So, the 64kB banks of a C128 with 1 megabyte of
internal memory are numbered from 0 to f.  On a 512kB-expanded C128, the
unique bank numbers are 0-1, 4-5, 8-9 and c-d, as there are only two MMU
banks.  For instance, the banks b and 9 are the same.  On a 256kB-expanded
C64, the bank numbers 0-3, 4-7, 8-b and c-f are the same, so there are 4
different banks.

Bank numbers from 10 to ff are for REU memory banks, i.e. the banks of a
512 kilobyte REU are numbered from 10 to 17.

As you can see from the prserver.asm source code, the PIA and REU expansions
are accessed through a 16kB window at $4000.  There's a bug in the plain
C128 version: any data read from $0-$400 will be fetched from bank 0.  The
version for the PIA expansion does not have this bug.


COMPILING

To compile, you need GNU C (tested with 2.5.8 and 2.6.2, any version
should do) and the dasm port made by Olaf Seibert.  It can be downloaded
from ftp.funet.fi:/pub/cbm/programming/dasm.tar.gz.

The software supports several different cables.  The transfer routines for
the different cables are in prtrans2.c, prtrans4.c, prtrans8.c and pramiga.c.
You will have to edit the Makefile to specify which cable (CABLEOBJ) and
default printer port to use.  The latter one is not required in the
Amiga version.  The Amiga version also allows the -DPRLINK88 option, which
uses a full 8-bit transfer.

Also, before compiling the prserver.prg daemon for the remote
computer, you have to edit the TARGET, RAMEXP and CABLE definitions in the
Makefile.  The definitions are as follows:

    definition    options
    ----------    -------
    TARGET        target system, i.e. vic20, c64, c128 etc.

    RAMEXP        none    no memory expansion installed
            piaexp    the PIA expansion for the C64 and the C128
                (ftp.funet.fi:/pub/cbm/documents/{256kB,1028})
            reuexp    Commodore RAM Expansion Unit
            pet96    PET 8096/8296 expansion

    CABLE        prlink     the default 8-bit/4-bit cable
            pc64     the 4-bit/4-bit cable used by the PC64 emulator
            c64net     the 4-bit/2-bit cable used by 64NET
            prlink88 fully 8-bit transfers with the pramiga cable

Also, you may need to change the following definitions in prserver.asm, if
using the PIA and/or REU expansions:

    pia        the PIA base address, e.g. $dff0
    reu        the REU base address, e.g. $df00
    actionreuplay    If you are using Action Replay and the REU
            simultaneously, set this to 1.


If you have several C= computers connected to different printer ports,
probably even using different cables, you have to compile several versions
of the programs for your configuration.  By default, all prlink client
programs are combined to one file, prmain, which will recognize the program
name and act accordingly.  If the program is called with prload, it will
work as prload.  Alternatively, you can use command line switches, like
prmain --prload, to change the operation.  I have compiled two different
client program packages, prmain8 for the prlink cable, and prmain4 for the
PC64 cable.  In my .cshrc, I have defined aliases like

alias prload4 'prmain4 --prload'
alias prsave4 'prmain4 --prsave'
alias prcart4 'prmain4 --prcart'
alias prrfile4 'prmain4 --prrfile'
alias prwfile4 'prmain4 --prwfile'
alias prdisk4 'prmain4 --prdisk -l ~/bin/prdisk.prg'

Actually, I should have several versions of these prdisk.prg, prrfile.prg
and prwfile.prg programs, one for each computer type.  Then I should have
aliases like prdisk4c128, prdisk8vic and so on.  If you have a better idea
how the prdisk, prwfile and prrfile clients should be implemented, feel free
to tell me.


PERFORMANCE OVERVIEW

The 64NET cable is supported only because of compatibility reasons, as it
is very slow.  Instead, you should use either the PC64 cable or my own
cable.  Here are some statistics:

Client: 486DX2/66 with 128kB cache running Linux, no processes running on
        the background
Server: Commodore 128D with 1 MB internal memory and 1 MB REU
Data block: 64 kilobytes
Cable: PC64

Server type                send    receive
===========                ====    =======
Commodore 128 with PIA mapped memory    3,83s    4,09s
Commodore 128 with REU, using REU    4,06s    4,34s
Commodore 128 (stock)            4,98s    5,55s
Commodore 64 with PIA mapped memory    7,25s    7,72s
Commodore 64 with REU, using REU    7,55s    8,07s
Commodore 64 (stock)            8,07s    8,01s

Note that the Commodore 64 version of the server tries to use the 2 MHz
mode of the Commodore 128.  Thus, on a Commodore 128 running in C64 mode,
the transfer times are about half of the rates listed above.


HARDWARE

The PC64 cable is the cable used by the Personal C64 emulator written and
marketed in Germany by Wolfgang Lorenz <[e-mail]>, and
has 4 data bits to both directions.  If you are using or are planning to use
this emulator, then you are best off using this cable.

The prlink cable supports 8 bit data transfers from the PC to the C= side,
and 4 bits from the C= to the PC.  It uses four bidirectional lines on the
PC.

And now for the cable pinouts.  Note that I disclaim any warranties, so
you are using these instructions at your own risk.  Do not insert the plug
to the user port the wrong way around, or you'll blow your printer port on
the PC with the 9 volt signal as I did.

The 64NET cable pinout won't be listed, as the 64NET documentation claims
that it is copyrighted.  Besides, including it would be a waste of space,
as other cables allow much faster protocols.  Here's the PC64 cable pinout:

             PC                C64        Comment

         GND    25   ------   A  GND      Ground
         D7      9   ------>  B  FLAG     Handshake signal
         ERR    15  <------   C  PB0      Data from C= to PC
         SEL    13  <------   D  PB1               "
         PE     12  <------   E  PB2               "
         ACK    10  <------   F  PB3               "
         D0      2   ------>  H  PB4      Data from PC to C=
         D1      3   ------>  J  PB5               "
         D2      4   ------>  K  PB6               "
         D3      5   ------>  L  PB7               "
         BUSY   11  <------   M  PA2      Handshake signal

My prlink cable is constructed as follows:

             PC                C64        Comment

         GND    25   ------   A  GND      Ground
         D3      5   ------>  B  FLAG     Handshake signal
         STROBE  1  <------>  C  PB0      Bidirectional data lines
         AUTO   14  <------>  D  PB1               "
         INIT   16  <------>  E  PB2               "
         SELECT 17  <------>  F  PB3               "
         D4      6   ------>  H  PB4      Data from PC to C=
         D5      7   ------>  J  PB5               "
         D6      8   ------>  K  PB6               "
         D7      9   ------>  L  PB7               "
         BUSY   11  <------   M  PA2      Handshake signal

Here is the pramiga cable, the only alternative for Amiga:

           Amiga               PET        Comment

         GND    22   ------   A  GND      Ground
         POUT   12   ------>  B  CA1      Handshake signal (strobe/flag)
         D0      2  <------>  C  PA0      Bidirectional data lines
         D1      3  <------>  D  PA1               "
         D2      4  <------>  E  PA2               "
         D3      5  <------>  F  PA3               "
         D4      6   ------>  H  PA4      Data from Amiga to PET
         D5      7   ------>  J  PA5               "
         D6      8   ------>  K  PA6               "
         D7      9   ------>  L  PA7               "
         BUSY   11  <------   M  CB2      Handshake signal (ack)


On the PET, I chose to use CB2 even though that pin is normally
connected to a speaker. I did this because it makes the cable identical
to the 64 and VIC cable, and allows you to use a single-sided connector.
Make sure though that it does not connect the top and bottom fingers!

Note that the lower user port connections are named ABCDEFHJKMMN,
skipping G and I.

On the Amiga 1000, pin 25 is not GND so I picked 22 instead which should
be GND on all Amiga models.  On the PC, all pins from 18 to 25 should be
GND.

The Amiga cable allows for two protocols: the prlink compatible 4-bit/8-bit
transfer, and a full 8-bit transfer, the option prlink88.

BOOTSTRAPPING

Type in the supplied "basic-listing", with proper modifications for your
hardware. Then run it, an on the Linux/Amiga side give the command "prload
prserver.prg". Now you should see a list of addresses and byte values
scroll by. If not, the connection does not work properly. These bytes are
not put in memory yet; for that you must make one final change as indicated
at the end of "basic-listing".

Once prserver.prg has been transferred, save it. The addresses it occupies
are printed by the basic program.

USING

Start the 6502 side by giving the command SYS [start address], where
[start address] is of course the first byte of the program. The server
will hook itself in the IRQ and you should get a READY prompt back
immediately. Now you can use the prload, prsave, etc programs from
the other side. These programs give their usage if you call them with
incorrect arguments (or no arguments at all).


CONTACTING THE AUTHORS

If you have any questions, e-mail me, Marko Mäkelä <[e-mail]>.
Questions related to the Amiga and PET versions should be directed to
Olaf Seibert <[e-mail]>.